staticaddr: fast-flag #1009

hieblmi · 2025-09-30T15:07:52Z

The fast flag enables the client to access change of a fractional amount swap faster. Since batching can delay the publishing of the on-chain swap transaction the client can pay a fee for faster access to optional change. A few examples of how this PR changes the command line arguments for fractional swaps.

loop static in 500000                                                 // Loop in exactly 500000 sats; auto-select deposits to cover the amount.
loop static in 500000 --fast                                         // Same as above, but request fast publication behavior (may cost more).
loop static in --all                                                 // Loop in the full balance of all eligible static-address deposits.
loop static in 500000 --all                                         // Loop in exactly 500000, select all eligible static-address deposits.
loop static in --utxo txid:vout                                     // Loop in exactly the specified deposit UTXO.
loop static in --utxo txid:vout --utxo txid:vout ...                 // Loop in the union of the listed deposit UTXOs.
loop static in 500000 --utxo txid:vout --utxo txid:vout ... --fast     // 500000 from selected deposits with fast publication behavior.

gemini-code-assist · 2025-09-30T15:08:56Z

Summary of Changes

Hello @hieblmi, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the static address loop-in functionality by introducing a 'fast' option. This feature allows users to prioritize the speed of on-chain transaction publishing for fractional change amounts, enabling quicker access to funds by bypassing standard batching delays. The implementation involves comprehensive updates across the system, from the command-line interface and API definitions to the database schema and the sweep batching mechanism, ensuring that the 'fast' preference is consistently handled and applied.

Highlights

Fast Flag Introduction: A new 'fast' flag has been introduced for static address loop-in swaps, allowing clients to request expedited publishing of on-chain transactions, particularly for change outputs.
Expedited Publishing: When the 'fast' flag is enabled, the sweep batcher will bypass its usual initial delay mechanism, leading to immediate publication of the swap transaction, albeit potentially at a higher fee.
Database Persistence: The 'fast' flag is now stored in the database for static address swaps, ensuring that the client's preference for expedited publishing is recorded and persisted.
API and CLI Integration: The new 'fast' flag has been integrated across the client's command-line interface, internal API definitions (gRPC and Swagger), and server-side logic to propagate and act upon this new preference.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a --fast flag for static address loop-in swaps, enabling expedited publishing of the on-chain transaction in exchange for a potentially higher fee. The implementation correctly propagates this flag from the CLI and RPC layers down to the server request, and the database schema is updated accordingly. The main feature appears to be well-implemented.

Additionally, a similar fast flag mechanism has been added to the sweepbatcher for client-side sweeps. However, this functionality seems to be unused in the current changes, which could lead to confusion. I've added a review comment to seek clarification on this part of the implementation.

sweepbatcher/sweep_batcher.go

hieblmi · 2025-10-01T18:56:08Z

looprpc/client.proto

+
+    /*
+    If set to true the server will immediately publish the swap in exchange for
+    a higher fee. This can be useful if the client expects change from a swap.


only available for swaps with change...

hieblmi · 2025-10-01T18:56:20Z

swapserverrpc/server.proto

    // has to pay when the sweeping transaction is broadcast.
    uint32 num_static_address_deposits = 7;
+
+    // If set, request the server to use fast publication behavior.


add description

bhandras

LGTM 🎉

cmd/loop/staticaddr.go

starius

LGTM! 🌴
Great work!

I left few proposals. The most important one is in sweepbatcher to let fast swaps batching. I proposed a way how to do it keeping the change small.

starius · 2025-10-06T17:48:14Z

looprpc/client.proto

    bool auto_select_deposits = 10;
+
+    /*
+    If set to true the server will immediately publish the swap in exchange for


Add a note that this field is only allowed for static loop-ins. If it is used in a regular loop-in, loopd should return an error.

starius · 2025-10-06T17:49:02Z

swapserverrpc/server.proto

    // has to pay when the sweeping transaction is broadcast.
    uint32 num_static_address_deposits = 7;
+
+    // If set, request the server to use fast publication behavior.


Add a note that this field is only allowed for static loop-ins. If it is used in a regular loop-in, loop server is expected to return an error.

starius · 2025-10-06T17:49:38Z

loopdb/sqlc/migrations/000020_static_address_fast_flag.down.sql

@@ -0,0 +1,2 @@
+-- Drop 'fast' flag from static_address_swaps
+ALTER TABLE static_address_swaps DROP COLUMN fast;


Line end is missing.

starius · 2025-10-06T17:49:42Z

loopdb/sqlc/migrations/000020_static_address_fast_flag.up.sql

@@ -0,0 +1,2 @@
+-- Add 'fast' flag to static_address_swaps, default false
+ALTER TABLE static_address_swaps ADD COLUMN fast BOOLEAN NOT NULL DEFAULT false;


Line end is missing.

starius · 2025-10-06T18:03:51Z

sweepbatcher/sweep_batcher.go

 // logged as a warning.
 type InitialDelayProvider func(ctx context.Context, numSweeps int,
-	value btcutil.Amount) (time.Duration, error)
+	value btcutil.Amount, fast bool) (time.Duration, error)


IIUC, true is never passed to this callback. If fast=true, there is a separate code path in spinUpBatch:

if cfg.initialDelayProvider == nil || fast { cfg.initialDelayProvider = zeroInitialDelay }

I propose to use this new argument instead of making a special case in spinUpBatch.

fast=true is passed on the delay provider on the server side.

starius · 2025-10-06T18:06:51Z

sweepbatcher/sweep_batcher.go

+	// If fast is set, we spin up a new batch which is published
+	// immediately.
+	if fast {
+		return b.spinUpNewBatch(ctx, sweeps, true)
+	}


This prevents batching fast sweeps. It makes sense to batch them to save on fees.

I propose to remove this if and track fastness per sweep. We can add the flag to sweep and modify batch.Run method to pass fast to b.cfg.initialDelayProvider call (the only place where initialDelayProvider is called).

It makes sense to add method isFast() for batch similar to isUrgent and call if from batch.Run for convenience.

And we don't need to pass fast to spinUpBatch anymore, because we can always deduce it from sweeps.

Thanks for the suggestion to briefly delay the publication of a fast batch to gather more fast swaps. This will be addressed in a separate PR.

starius · 2025-10-06T18:09:53Z

loopd/swapclient_server.go

 		Private:        req.Private,
 		Initiator:      defaultLoopdInitiator,
 		NumDeposits:    uint32(numDeposits),
+		Fast:           req.Fast,


I propose to check here that if req.Fast is set, we make sure that the swap is static. Otherwise fail. Just as a sanity check measure.

added a sanity check.

starius · 2025-10-06T18:13:04Z

cmd/loop/staticaddr.go

+			Usage: "expedited publishing of the change output if " +
+				"the swap creates one. This results in a " +
+				"higher swap fee.",
+		},


I propose to rephrase it to make the purpose clearer:

Usage: "complete the swap faster by paying a higher fee, so the change output is available sooner",

added this description

starius · 2025-10-06T18:15:03Z

cmd/loop/staticaddr.go

-				"swapped from the selected deposits. If there" +
-				"is change it is sent back to the static " +
-				"address.",
-		},


Can we keep previous flag as well? So it is possible to set it via --amount. Some people may prefer this, e.g. in scripts where each argument is on a separate line. Positional argument is good for manual use.

That makes sense, I re-added the flag.

starius · 2025-10-07T06:18:52Z

CLI is broken:

$ ~/fast-flag/loop --network signet static in --utxo b7c34d293e816cdcb102f1e2dcfaba9c4f553356a881fcc042ad6522da972176:0
On-chain fees for static address loop-ins are not included.
They were already paid when the deposits were created.

Previously deposited on-chain:                  0 sat
Receive off-chain:                          -1568 sat
Estimated total fee:                         1568 sat

CONTINUE SWAP? (y/n): n

Also:

$ ~/fast-flag/loop --network signet static in --all
On-chain fees for static address loop-ins are not included.
They were already paid when the deposits were created.

Previously deposited on-chain:                  0 sat
Receive off-chain:                          -6399 sat
Estimated total fee:                         6399 sat

CONTINUE SWAP? (y/n):

I think this also exists in master.

It seems to pass QuoteRequest{Amt: 0} in displayInDetails. We have variable allDeposits in that function (staticAddressLoopIn), we can deduce the amount from it if user doesn't specify anything.

hieblmi · 2025-10-07T06:43:14Z

CLI is broken:

Yes thanks, I noticed this bug a while ago and have a fix on my todo list. Its because the quoting part doesn't have access to the utxo amount yet.

…cAddressLoopInRequest

--fast allows the client to expedite the publishing of on-chain swap transactions with change, e.g. if --amount was specified.

gemini-code-assist bot reviewed Sep 30, 2025

View reviewed changes

sweepbatcher/sweep_batcher.go Show resolved Hide resolved

hieblmi force-pushed the fast-flag branch from d2000da to 7415c02 Compare October 1, 2025 06:53

hieblmi requested review from bhandras, sputn1ck and starius October 1, 2025 06:54

hieblmi force-pushed the fast-flag branch from 7415c02 to 2917e93 Compare October 1, 2025 07:09

hieblmi commented Oct 1, 2025

View reviewed changes

alexbosworth mentioned this pull request Oct 1, 2025

version: bump version to v0.31.4-beta #1010

Open

levmi assigned hieblmi Oct 2, 2025

bhandras approved these changes Oct 6, 2025

View reviewed changes

cmd/loop/staticaddr.go Show resolved Hide resolved

hieblmi force-pushed the fast-flag branch 3 times, most recently from 407d912 to d5567e2 Compare October 6, 2025 16:19

starius approved these changes Oct 6, 2025

View reviewed changes

hieblmi added 5 commits October 7, 2025 08:51

looprpc: fast flag for QuoteRequest and StaticAddressLoopInRequest

8464e4c

swapserverrpc: fast flag for ServerLoopInQuoteRequest and ServerStati…

83c8666

…cAddressLoopInRequest

loopdb: staticaddr fast flag migration and queries

92a8726

sweepbatcher: fast-flag enables zero delay publishing

422bcd7

staticaddr: fast-flag support

51258af

--fast allows the client to expedite the publishing of on-chain swap transactions with change, e.g. if --amount was specified.

hieblmi force-pushed the fast-flag branch from d5567e2 to 74b2e34 Compare October 7, 2025 07:11

hieblmi added 4 commits October 7, 2025 09:12

loopd: fast-flag in GetLoopInQuote and StaticAddressLoopIn

168420c

loop: handle fast-flag in legacy loop-in

aaeeefe

cmd: staticaddr fast-flag support

2548522

cmd: positional amount flag for staticaddr loop-in

f05b0e6

hieblmi force-pushed the fast-flag branch from 74b2e34 to f05b0e6 Compare October 7, 2025 07:15

hieblmi merged commit c1ab1f3 into lightninglabs:master Oct 7, 2025
4 checks passed

hieblmi deleted the fast-flag branch October 7, 2025 08:03

hieblmi mentioned this pull request Oct 7, 2025

staticaddr: fix static quote #1014

Merged

		@@ -0,0 +1,2 @@
		-- Drop 'fast' flag from static_address_swaps
		ALTER TABLE static_address_swaps DROP COLUMN fast; No newline at end of file

		@@ -0,0 +1,2 @@
		-- Add 'fast' flag to static_address_swaps, default false
		ALTER TABLE static_address_swaps ADD COLUMN fast BOOLEAN NOT NULL DEFAULT false; No newline at end of file

staticaddr: fast-flag #1009

staticaddr: fast-flag #1009

Uh oh!

Conversation

hieblmi commented Sep 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Sep 30, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bhandras left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

starius left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

starius commented Oct 7, 2025

Uh oh!

hieblmi commented Oct 7, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

hieblmi commented Sep 30, 2025 •

edited

Loading